home *** CD-ROM | disk | FTP | other *** search
/ MacHack 1994 / MacHack 1994.toast / MacHack™ 1987-1994 / MacHack™ '91 / '91 Attendee Contributions / Handling Apple events with HC next >
Encoding:
Text File  |  1991-06-20  |  5.6 KB  |  144 lines  |  [TEXT/GEOL]
  1.  
  2. When HyperCard 2.1 receives an Apple event, it sends an appleEvent
  3. message to the current card.  That means that you can respond to Apple
  4. events with HyperTalk scripts.  But before you try to write such scripts,
  5. there are some terms and conventions you should be familiar with.
  6.  
  7. The figure
  8. ----------
  9.  
  10. Apple events are like a package full of raw materials that arrive at a
  11. factory.  They have a return address on them -- in HyperTalk, a string of
  12. the form "Zone:Macintosh:Program".  They have an explanation of what their
  13. contents are for -- the class and id, which together consititute a verb,
  14. directing the receiver what do to with the package.  And of course there
  15. are the contents themselves -- the event parameters.
  16.  
  17. When you get one of these packages, you have to unpack it before you can
  18. make something out of the raw materials inside.  But you can't just rip
  19. into the package willy-nilly.  You have to ask for what you want, by name.
  20. "Give me the snod." "OK, now give me the lerd."  You unpack the contents,
  21. one by one, and make out of them whatever you're directed to make by the
  22. class and id.
  23.  
  24. The catch is that the package doesn't come with a packing list.  You're
  25. supposed to know what's in it -- you have a big book that tells you that
  26. whenever you get a package that you're supposed to make into a "wild plum",
  27. it's supposed to have a "bork", a "flam", and a "nitz" inside of it.  So
  28. you unpack the bork, the flam, and the nitz, and then you make the wild
  29. plum out of them and send it back.
  30.  
  31.     Apple event = package
  32.     class and id = terse directions for what to do with the package
  33.     parameters = contents of the package
  34.     keywords = names for each thing in the package
  35.  
  36.  
  37. The lesson
  38. ----------
  39.  
  40. In HyperTalk, when you handle the appleEvent message, you first look at
  41. the class and id, and they tell you what you're supposed to do with the
  42. event.  If it's an event that you know how to handle, you already know what
  43. the parameters are -- you've agreed with the sender in advance on what's
  44. supposed to be in it, or it's a standard Apple event defined in the
  45. voluminous standard documentation.  So you unpack the parameters with the
  46. "request" command, manipulate them, and send back what you made out of them
  47. with the "reply" command.
  48.  
  49. The script might look like this:
  50.  
  51.    on appleEvent class,id,sender
  52.      if class & id is "wildplum" then
  53.        request ae data with keyword "bork"
  54.        if the result is not empty then   -- probably "Not found"
  55.          reply error "Expected a bork but got none."
  56.          exit appleEvent
  57.        end if
  58.        put it into theBork
  59.        request ae data with keyword "flam"
  60.        .
  61.        .
  62.        .
  63.        .
  64.        get wildPlumMakingFunction(theBork,theFlam,theNitz)  -- process it
  65.        reply it  -- send back the reply
  66.      else pass appleEvent  -- we don't recognize this event; pass it on
  67.    end appleEvent
  68.  
  69.  
  70. Keywords
  71. --------
  72.  
  73. Think of a keyword for a piece of data in the package as its name -- it's
  74. the handle you need to pull it out of the package.  Asking for a parameter
  75. by keyword is the same as asking for a piece of raw material by name.
  76.  
  77. Keywords are arbitrary.  Whoever invents an Apple event makes them up, on
  78. the spot, out of the blue, to name the pieces of data that go along with
  79. the event.  The standard Apple events that have already been defined, along
  80. with the keywords for their required and optional parameters, are described
  81. in the Apple Event Registry.
  82.  
  83.  
  84. The direct object
  85. -----------------
  86.  
  87. Many Apple events arrive with just one piece of raw material in them, or
  88. one piece that's more important than the others.  By convention, this piece
  89. is given the keyword "----" and is referred to in the Apple event
  90. documenation as "the direct object" or "the direct parameter".  These are
  91. pretty ugly names, so in HyperTalk you can just call it the "data" and
  92. leave off the keyword specification -- HyperCard will know what you're
  93. talking about.
  94.  
  95.    request appleEvent data
  96.  
  97. This is equivalent to the following statement.
  98.  
  99.    request appleEvent data of keyword "----"
  100.  
  101. The direct object for the 'odoc' event is the list of documents to open.
  102. The direct object for the 'dosc' event is the script to execute.  And so
  103. on.
  104.  
  105.  
  106. Event attributes
  107. ----------------
  108.  
  109. Apple events come along with more than just an address, a verb, and pieces
  110. of data.  They also come with modifiers, or "attributes", which you can
  111. think of as "special handling instructions".  The class, id, and sender are
  112. all attributes also, but HyperCard gives you these automatically as
  113. parameters to the appleEvent message.  The timeout value, the transaction
  114. id, and the return id -- the identifier you put on the reply so that the
  115. sender knows, when his wild plum arrives, which package you made it out of
  116. -- are additional attributes.  If you need to look at these, the "request"
  117. command will let you.
  118.  
  119. You can get the return id,
  120.  
  121.    request appleEvent return id
  122.    request appleEvent data of keyword "rtid"  -- same thing, only uglier
  123.  
  124. the timeout value,
  125.  
  126.    request appleEvent data of keyword "timo"
  127.  
  128. the transaction id,
  129.  
  130.    request appleEvent data of keyword "tran"
  131.  
  132. and whatever else you think you need, as long as you know its keyword.  We
  133. have special forms of the request command for the class, id, sender, direct
  134. object, and return id -- for everything else, you have to tell HyperCard
  135. what you want by keyword.
  136.  
  137.    request appleEvent class   -- gives you the class attribute
  138.    request appleEvent id      -- gives you the id attribute
  139.    request appleEvent sender  -- gives you the sender attribute
  140.    request appleEvent data    -- gives you the direct object parameter
  141.    request appleEvent return id   -- gives you the return id attribute
  142.  
  143. Author: CALHOUN.K
  144.